Loading...
 

Setting up the WebService

Setting up the WebService

ClassiX as WebService without web server (HTTP server)

The following steps must be taken so that ClassiX® can be addressed as a WebService:

  1. The ClassiX® client must be installed.
  2. In the classix.ini the DLL "cxivsa_EXT_" must be added to the list of dlls.
  3. To set up HTTPS, the following environment variables must be set via the batch file and the respective files must be available.
    SET CX_HTTPS_KEY_FILE=%CX_ROOTDIR%\webservice\server.key
    SET CX_HTTPS_CERT_FILE=%CX_ROOTDIR%\webservice\server.crt
  4. The web service should be started with the following commands via the "Web Service Cockpit". The Web Service Cockpit displays all incoming and outgoing messages.

    // Open web service window

    SendMsg(WEB_SERVICE_MANAGER)

    // Choose port 443 and start web services

    "TRUE PutValue(WebServiceWin, Port443Rdo) Widget(WebServiceWin, Port443Rdo) SendMsg(SELECT, DIRECT) Widget(WebServiceWin, StartBtn) SendMsg(SELECT, DIRECT)" SendMsg(TEST_WEB_SERVICE_MANAGER)

  5. Alternatively, the WebService can also be started directly. This is best done in the classix.cxp.
    GetManager(WEB_SERVICE) Call(Start)
    The WebService must then run on port 443. This can be accessed via
    443 GetManager(WEB_SERVICE) Put(port)
    can be set. However, this port is preset in the manager WEB_SERVICE.

As a test, the following URL can then be called up in the browser:

https://localhost/WEB_READ_EXECUTE?p=GetValue(ControlWin)

As a result, the following error message should appear in the browser:

{"status": "false", "statusMessage": "Cookie with SessionID was not transferred"}

Access from another ClassiX Client can also be tested.

DropAll
// Create HTTP Request COM Object
Var(g_winhttp)
CreateTransObject(CX_COM_OBJECT) -> g_winhttp
"WinHttp.WinHttpRequest.5.1" g_winhttp CallWeak(CreateFromProgID)
// Switch OFF error message about wrong certifacte keys
13056 4 g_winhttp Call(PutOption)
// Send a "POST" message with login data
"POST" "https://localhost/WEB_WRITE_LOGIN?sessionUserId=cx&password=cola" FALSE g_winhttp Call(Open)
// Receive data
g_winhttp Call(Send)
g_winhttp Call(GetResponseText)
// Show data
Attention

ClassiX as WebService with Web server (HTTP server)

ClassiX® can also be addressed via an HTML interface using a web browser. In this case, both the installation of a web server (HTTP server) and the setup of a ClassiX® client are necessary. The web server performs two tasks. On the one hand, it provides the HTML pages. On the other hand, it forwards the requests (HTTP request) to the ClassiX® client.

Installation of the proxy server (Evaluate)
  1. The installation and configuration files required for the installation are checked into Perforce in the following directory: Y:/ClassiX/Evaluate/WebService/ProxyServer/
  2. Run xampp-win32-1.8.3-1-VC11-installer.exe and ignore any error messages and warnings that may appear.
  3. In the "Select Components" dialogue, deselect everything that can be deselected.
    proxy-select_components.png
  4. Installation directory best left at C:\xampp.
  5. After the installation the XAMPP Control Panel can be started.
  6. Copy httpd.conf to C:\xampp\apache\conf and overwrite the file there.
  7. Copy httpd-proxy.conf and httpd-ssl.conf to C:\xampp\apache\conf\extra and overwrite the files there.
  8. If the installation directory is C:\xampp, continue with step 10.
  9. In the httpd.conf line 37 Adjust directory to INSTALLATIONPATH/apache
  10. In the httpd-ssl.conf line 86 adjust directory. You can choose any directory. From here Apache reads the .html files it delivers.

    If the DocumentRoot variable refers to a directory outside the proxy server directory, as in the following example, special properties must be defined for this directory. (The following lines must be written in httpd-ssl.conf. line 86). 

    DocumentRoot "Y:/ClassiX/Evaluate/WebService/htdocs"

<Directory "Y:/ClassiX/Evaluate/WebService/htdocs">
   Options Indexes FollowSymLinks Includes ExecCGI
   AllowOverride All
   Require all granted
</Directory>

  11. In the httpd-ssl.conf line 89+90 adjust directories accordingly.
  12. To call up a "/view/"url, i.e.tocall up a window directly in ClassiX, an ".htaccess" entry must be inserted in the "htdocs" directory as follows:
  13. Options +FollowSymLinks
RewriteEngine On
RewriteRule ^view/(.*)$ /index.html#/view/$1 [R,QSA,NC,NE,L]
  14. Now you can start via the XAMPP Control Panel(start menu) and start the Apache server.
  15. Start your browser and go to https://localhost.
Access to the ClassiX® WebService via the proxy server

The ClassiX® must run under port 444.

444 GetManager(WEB_SERVICE) Put(port)
FALSE GetManager(WEB_SERVICE) Put(useSSL)
GetManager(WEB_SERVICE) Call(Start)

Once both servers have been started, a message can be sent to the ClassiX® system via the URL https://127.0.0.1/send/MESSAGENAME. All URLs that do not begin with /send/ are interpreted as files relative to the directory configured in step 9 (default: C:\xampp\htdocs). All images/HTML files/script files etc. are stored there.

Install certificate

Since the server uses its own certificate when accessed via HTTPS, browsers should display a warning message when trying to open the page via https://localhost. How to fix the problem is described here.

Customisation options

The file C:\xampp\apache\conf\extra\httpd-proxy.conf should contain the following two lines

14   ProxyPass /send/ http://127.0.0.1:444/ keepalive=On retry=1 acquire=3000 timeout=600 connectiontimeout=10
15   ProxyPassReverse /send/ http://127.0.0.1:444/

Setting up forwarding to another machine

If proxy server and ClassiX instance are not running on the same machine, the IP address above has to be replaced by the corresponding address of the machine running the ClassiX instance. This can also be the host name.

Switching between HTTPS and HTTP

General communication scheme: 

Browser <===[HTTPS]===> Proxy <===[HTTPS oder HTTP]===> ClassiX

If in these lines the protocol http is replaced by https, the requests received by the proxy are not forwarded to the ClassiX instance in normal HTTP (plain text) but as HTTPS (encrypted).
If proxy and Classix instance are running on the same machine, the use of HTTP is not critical, because the requests transmitted in clear text (and possibly also passwords) cannot be intercepted. If Proxy and Classix are running on different machines connected by an insecure network, HTTPS should also be considered between Proxy and ClassiX.

The use of HTTPS between proxy and ClassiX has on the one hand a performance disadvantage, on the other hand the stability of the web application suffers. Up to now it happens again and again that the proxy receives answers from the ClassiX instance which it considers invalid. Therefore it is advisable to start ClassiX and proxy on the same machine if possible and to use HTTP between ClassiX and proxy.

If no proxy is used and ClassiX is addressed directly (by a browser or web service), the use of HTTPS is not critical.

According to the configuration of the proxy, the ClassiX instance must also be configured in such a way that both use the same protocol. By default, HTTPS is active for ClassiX. To disable HTTPS, the following code must be executed:

FALSE GetManager(WEB_SERVICE) Put(useSSL)

For security reasons, the connection between proxy and browser should never be switched to HTTP, as this allows all form data (including user names and passwords) to be transferred in plain text and read by third parties.

Changing the port on which the ClassiX instance receives requests

Port usage in the default configuration: 

Browser ====>[Port443] Proxy ====>[Port444] ClassiX
             \--------- gleiche Maschine-----------/

In the configuration suggested above, requests from the proxy server are forwarded to port 444 of the ClassiX instance. If the port is already in use by another program on the target machine, the web service cannot be started there and another port has to be used.

To do this, the port must be changed to a free port in the configuration file and in InstantView this must also be adjusted (before the service is started). If no port is specified, the ClassiX instance starts on port 443 by default, but this port cannot be used in the configuration file, because the proxy server is already running on this port.

newPort GetManager(WEB_SERVICE) Put(port)

Changing the forwarding directory

In the standard configuration, all requests called with the URL /send/*** are forwarded to the ClassiX instance with the URL /***. All other calls are interpreted as accesses to files relative to the DocumentRoot (see point 10 of the installation) of the proxy. This setting has the consequence that a directory called "send" in the proxy cannot be delivered to the browser.

If the URL /send/ is replaced by / in the configuration, all requests coming to the proxy are forwarded to the ClassiX instance.

Related topics